redlock

What is redlock?

Redlock is a distributed lock manager for Node.js using Redis. It implements the Redlock algorithm, which is a method for achieving distributed mutual exclusion. This is useful for ensuring that only one process can access a shared resource at a time, even in a distributed system.

What are redlock's main functionalities?

Acquiring a Lock

This feature allows you to acquire a lock on a resource. The lock is held for a specified duration (2000 ms in this example). If the lock is successfully acquired, you can perform your operations and then release the lock.

const Redlock = require('redlock');
const redis = require('redis');
const client = redis.createClient();
const redlock = new Redlock([client]);

redlock.lock('locks:resource', 2000).then(function(lock) {
  // Do something with the lock
  console.log('Lock acquired');
  // Release the lock
  return lock.unlock();
}).catch(function(err) {
  console.error('Failed to acquire lock', err);
});

Extending a Lock

This feature allows you to extend the duration of an existing lock. This is useful if you need more time to complete your operations while holding the lock.

const Redlock = require('redlock');
const redis = require('redis');
const client = redis.createClient();
const redlock = new Redlock([client]);

redlock.lock('locks:resource', 2000).then(function(lock) {
  // Extend the lock
  return lock.extend(2000);
}).then(function(lock) {
  console.log('Lock extended');
  // Release the lock
  return lock.unlock();
}).catch(function(err) {
  console.error('Failed to extend lock', err);
});

Handling Lock Failures

This feature demonstrates how to handle failures when acquiring or maintaining a lock. If an error occurs, it is caught and handled appropriately.

const Redlock = require('redlock');
const redis = require('redis');
const client = redis.createClient();
const redlock = new Redlock([client]);

redlock.lock('locks:resource', 2000).then(function(lock) {
  // Do something with the lock
  console.log('Lock acquired');
  // Simulate a failure
  throw new Error('Something went wrong');
}).catch(function(err) {
  console.error('Failed to acquire or maintain lock', err);
});

Other packages similar to redlock

node-redlock

node-redlock is another implementation of the Redlock algorithm for Node.js. It provides similar functionality to the redlock package, allowing you to acquire, extend, and release distributed locks using Redis. The main difference is in the API design and some additional features like automatic retry mechanisms.

redis-lock

redis-lock is a simpler package for distributed locking using Redis. It provides basic lock and unlock functionality but does not implement the full Redlock algorithm. It is easier to use but may not be as robust in a highly distributed environment.

redlock-js

redlock-js is another package that implements the Redlock algorithm. It offers similar features to the redlock package, including acquiring, extending, and releasing locks. It also provides additional configuration options for customizing the lock behavior.

README

Redlock

This is a node.js implementation of the redlock algorithm for distributed redis locks. It provides strong guarantees in both single-redis and clustered redis environments, and is fault tolerant in the latter.

Installation

npm install --save redlock

Configuration

Redlock can use node redis or any compatible redis library to keep its client connections.

A redlock object is instantiated with a required options parameter and at least one redis client parameter. Properties of the Redlock object should NOT be changed after it is first used, as doing so could have unintended consequences for currently-processing locks.

var client1 = require('redis').createClient(6379, 'redis1.example.com');
var client2 = require('redis').createClient(6379, 'redis2.example.com');
var Redlock = require('redlock');

var redlock = new Redlock(
	{
		// the expected clock drift; for more details
		// see http://redis.io/topics/distlock
		driftFactor: 0.01,
		
		// the max number of times Redlock will attempt
		// to lock a resource before erroring
		retryCount:  3,
		
		// the time in ms between attempts
		retryDelay:  200
	},
	
	// you should have one client for each redis node
	// in your cluster
	client1,
	client2
);

Usage

###Locking & Unocking

// the string identifier for the resource you want to lock
var resource = 'locks:account:322456';

// the maximum amount of time you want the resource locked,
// keeping in mind that you can extend the lock up until
// the point when it expires
var ttl = 1000;

redlock.lock(resource, ttl, function(err, lock) {

	// we failed to lock the resource
	if(err) {
		// ...
	}
	
	// we have the lock
	else {


		// ...do something here...


		// unlock your resource when you are done
		lock.unlock();
	}
});

###Locking and Extending

redlock.lock('locks:account:322456', 1000, function(err, lock) {

	// we failed to lock the resource
	if(err) {
		// ...
	}
	
	// we have the lock
	else {


		// ...do something here...


		// if you need more time, you can continue to extend
		// the lock until it expires
		lock.extend(1000, function(err, lock){

			// we failed to extend the lock on the resource
			if(err) {
				// ...
			}


			// ...do something here...


			// unlock your resource when you are done
			lock.unlock();
		}
	}
});

API Docs

###Redlock.lock(resource, ttl, callback)

• resource (string) resource to be locked
• ttl (number) time in ms until the lock expires
• callback (function) callback returning:
  • err (Error)
  • lock (Lock)

###Redlock.unlock(lock, callback)

• lock (Lock) lock to be released
• callback (function) callback with no returning arguments

###Redlock.extend(lock, ttl, callback)

• lock (Lock) lock to be extended
• ttl (number) time in ms to extend the lock's expiration
• callback (function) callback returning:
  • err (Error)
  • lock (Lock)

###Lock.unlock(callback)

• callback (function) callback with no returning arguments

###Lock.extend(ttl, callback)

• ttl (number) time in ms to extend the lock's expiration
• callback (function) callback returning:
  • err (Error)
  • lock (Lock)